boilerplate code

https://en.wikipedia.org/wiki/Boilerplate_code

Journaux liées à cette note :

J'estime le temps de lecture de cette note à 10 minutes

Je profite d'une discussion entre deux amis au sujet de just et make pour partager mon point de vue et mes pratiques sur ce sujet.

Je tiens tout de suite à préciser que c'est un sujet qui me tient à cœur, parce qu'il m'irrite fortement : j'ai lutté pendant des années avec la mauvaise Developer eXperience de l'outil make dans mes projets, et je continue à voir tant de développeurs s'entêter à utiliser un outil dont la raison d'être est la résolution de dépendances basée sur les timestamps de fichiers — or, il me semble que cette fonctionnalité n'est probablement jamais utilisée, sauf dans les projets C ou C++.

Tout d'abord, je souhaite commencer par lister quelques éléments de complexité des makefile.

Quelques exemples de complexité accidentelle apportée par Make

Chaque ligne est un sous-shell indépendant et ça c'est super pénible, exemple :

# Le "cd" n'a aucun effet sur la ligne suivante
broken-cd:
	cd /tmp
	ls    # ← liste le répertoire original, pas /tmp

Une solution de contournement est d'utiliser des backslashes pour continuer la ligne, mais cela complique la lisibilité :

build:
    cd /tmp && \
    ls && \
    echo "done"

Par défaut, Make utilise sh et non pas bash ou zsh et ne supporte pas la construction [[ ]], les tableaux, etc qui cassent silencieusement. Exemple de code qui ne fonctionne pas :

check-env:
	@if [[ -z "$(ENV)" ]]; then \
		echo "ENV is not set"; \
		exit 1; \
	fi
	@echo "ENV = $(ENV)"

L'indentation du contenu des rules doit être une tabulation (pas des espaces)
Les $ doivent être doublés pour le shell, sinon make l'interprète, exemple :

greet:
	@MSG="Hello $(APP_NAME)" && \    # $(APP_NAME) → résolu par make ✓
	echo $$MSG                        # $$MSG → variable bash du sous-shell ✓
	@echo $(MSG)                      # $(MSG) → make cherche "MSG" → vide ! ✗

# Piège 3 : le $ doit être doublé pour bash, sinon make l'interprète
list:
	@for i in 1 2 3; do echo $$i; done   # ✓ correct
	@for i in 1 2 3; do echo $i; done    # ✗ make interprète $i → vide

Le préfixe "-" permet d'ignorer les erreurs d'une commande est une convention propre à makefile, sans équivalent dans Bash

clean:
	-rm -rf build/    # sans "-", make s'arrête si build/ n'existe pas
	-docker rmi $(APP_NAME)

Par défaut, make affiche chaque commande avant de l'exécuter. Pour le supprimer, il faut préfixer chaque ligne avec @ :

build:
    echo "Building..."      # affiche : echo "Building..." puis : Building...
    @echo "Building..."     # affiche seulement : Building...

Du coup, dans la pratique, on se retrouve à préfixer toutes les lignes avec @ :

deploy:
    @echo "Deploying..."
    @docker build -t myapp .
    @kubectl apply -f k8s/

Nécessité d'ajouter des .PHONY

Pourquoi tant de difficulté pour lancer de simples commandes ?

À chaque fois que je rencontrais des problèmes avec make, je culpabilisais. Je me disais que c'était de ma faute, que tout le monde utilisait make et qu'il devait y avoir une bonne raison. Je voyais bien que mon expérience de développeur (DX) était mauvaise, que je n'avais pas besoin de résolution de dépendance… mais je me disais que je devais utiliser make, et que mon erreur était de ne pas avoir pris le temps de lire sa documentation.
Alors je replongeais régulièrement dans les 16 chapitres de la documentation de make et je me demandais pourquoi je devais apprendre la syntaxe de make en plus de celle de bash. Et au final, je finissais même par détester Bash en plus de make.

Pourquoi tout cela était-il aussi compliqué, alors que je voulais seulement lancer de simples commandes et intégrer quelques conditions dans mes scripts ?

La recherche d'alternative

En 2018, la douleur des makefiles revenait souvent dans nos discussions en interne, au sein de mon équipe, et on cherchait régulièrement des alternatives. Parmi les pistes étudiées :

Task, en Golang, apparu en 2017 — je l'ai testé et ai fortement envisagé de l'adopter
Pydoit, en Python, démarré en 2008
Rake, en Ruby, lancé en 2003 — alors que je ne maîtrise pas le Ruby et que, par goût personnel, j'évite au maximum d'intégrer ce type de projet dans mes stacks
CMake, qu'un collègue avait exploré

Fin 2018, la prise de conscience

Fin 2018, je ne me souviens plus pour quelle raison, en parcourant le code source de Terraform, je suis tombé sur le dossier scripts/) de Terraform.

├── ...
├── Makefile
├── ...
├── scripts
│   ├── build.sh
│   ├── changelog-links.sh
│   ├── changelog.sh
│   ├── copyright.sh
│   ├── debug-terraform
│   ├── exhaustive.sh
│   ├── gofmtcheck.sh
│   ├── gogetcookie.sh
│   ├── goimportscheck.sh
│   ├── staticcheck.sh
│   ├── syncdeps.sh
│   └── version-bump.sh
└── ...

Et un fichier makefile minimaliste qui lance simplement des fichiers Bash :

$ cat Makefile
protobuf:
        go run ./tools/protobuf-compile .

fmtcheck:
        "$(CURDIR)/scripts/gofmtcheck.sh"

importscheck:
        "$(CURDIR)/scripts/goimportscheck.sh"

staticcheck:
        "$(CURDIR)/scripts/staticcheck.sh"

exhaustive:
        "$(CURDIR)/scripts/exhaustive.sh"

[...snip...]

Et, ce jour-là, je me suis senti très stupide d'avoir passé tant de temps à trouver une solution qui était en réalité très simple, à portée de main !

Je pense aussi que le fait que cette méthode ait été utilisée par Mitchell Hashimoto en personne, dans Terraform, m'a probablement donné une sorte d'autorisation d'utiliser cette approche.

J'ai compris que je pouvais simplement me passer de make.

2019 à 2026 : utilisation de simples scripts Bash

Suite à ma prise de conscience de fin 2018, j'ai appliqué un principe que je nomme "enlever des couches" : plutôt que d'ajouter une technologie pour résoudre un problème, réfléchir à ce que peut enlever pour réduire la complexité — et, par la même, peut-être supprimer le problème lui-même. C'est une vigilance consciente contre le biais cognitif du cargo cult : la tendance à reproduire des pratiques par habitude ou imitation, sans vraiment les comprendre ni les justifier.

En appliquant ce principe, il m'a semblé que je pouvais simplement enlever make — sans avoir à le remplacer par un outil tel que Task qui aurait été une couche supplémentaire dont je n'avais probablement pas besoin.

J'ai même pris conscience qu'en plaçant tous mes scripts dans un dossier ./scripts/, je bénéficiais nativement de l'autocomplétion de mes commandes par le filesystem — tout comme ce que proposait aussi make.

Par exemple :

make up devenait ./scripts/up.sh
make build devenait ./scripts/build.sh
make clean devenait ./scripts/clean.sh
etc.

Et surtout, je pouvais désormais pleinement me concentrer sur ma maîtrise de Bash pour améliorer l'expérience de développeur (DX) de mes kits de développement.

L'astuce du cd automatique

Pour exécuter ces commandes sans se préoccuper du dossier courant, j'ai ajouté la ligne suivante au début de chaque script :

cd "$(dirname "$0")/../"

Cela permet de lancer ./scripts/up.sh depuis la racine du projet comme depuis un sous-répertoire (cd subproject && ../scripts/up.sh), et le script s'exécutera toujours depuis le dossier parent de scripts.

Voici le boilerplate code qu'utilise la quasi-totalité de mes scripts :

#!/usr/bin/env bash
set -e

cd "$(dirname "$0")/../"

...

Mais "make" est un standard ?

L'argument revient souvent : « make est un standard, tout le monde le connaît, un nouveau contributeur saura immédiatement quoi faire. ».

Seulement voilà : la partie « standard » de make, celle que tout le monde utilise réellement, c'est make <target> — et c'est exactement ce que fait ./scripts/<target>.sh, sans syntaxe supplémentaire, sans pièges de tabulations, sans résolution de dépendances par timestamps dont on ne veut probablement pas.

Il me semble que cet argument touche au cargo cult : on place un Makefile à la racine du projet par habitude, sans vraiment tirer parti des capacités qui justifient l'existence même de make.

De plus, si l'on parle de standard, bash est probablement au moins aussi universel que make. Et écrire un script bash est sans doute plus accessible pour un développeur que d'apprendre les subtilités du makefile ($ doublés, sous-shells, .PHONY, @, -, etc.).

Il me semble donc que l'argument du "standard" est légitime — mais mon choix de ne plus utiliser make n'est pas un obstacle pour autant : si ./scripts/up.sh est clairement documenté dans le README, je pense que n'importe quel développeur comprendra sans difficulté son usage et sa fonction. Pas besoin de connaître make pour exécuter un script bash dont le nom est explicite.

Retour d'expérience : 4 ans, de 2 à 10 développeurs

J'ai utilisé cette méthode avec succès pendant 4 ans, en passant de 2 à 10 développeurs, sans que j'aie constaté de friction. À ma connaissance, personne n'a eu de difficulté avec ce système d'exécution des scripts et, il me semble, personne ne m'a suggéré de les remplacer par autre chose.

Et Just, alors ?

J'ai découvert just en 2022, puis je l'ai vu gagner en popularité à partir de 2023 (199 commentaires sur HackerNews) :

J'ai failli me laisser tenter. Mais je n'avais aucune douleur avec mes scripts, j'étais pleinement satisfait — et conformément au principe d'enlever des couches, ajouter une couche supplémentaire n'avait aucun intérêt.

D'autre part, just est riche en fonctionnalités et sa documentation est déjà importante : il me semble que c'est beaucoup à apprendre pour un outil dont je n'ai pas besoin.

Et puis j'ai craqué pour Mise Tasks

Je suis un grand utilisateur de Mise et dernièrement ce projet a ajouté la fonctionnalité Tasks. Et au grand désespoir de mon ami Alexandre — qui me fait régulièrement remarquer cette contradiction —, j'ai craqué, j'ai commencé à utiliser cette fonctionnalité en janvier 2026. Je n'ai pas d'argument solide à avancer ; sans doute un mélange de curiosité et d'affection pour Mise.

Contrairement à just, la fonctionnalité task de Mise reste minimaliste et est compatible avec mon paradigme : le if dans l'exemple ci-dessous est du Bash standard — pas besoin de $$, de \, de sous-shells par ligne. J'écris du Bash et rien d'autre.

D'autre part, Mise est déjà au cœur de mes development kit, je l'utilise à depuis 2023 à la place de Asdf pour installer du tooling de développement. Depuis 1 an, j'ai remplacé direnv par Mise. Par conséquent, ce n'est pas une dépendance en plus à ajouter à mes projets.

Mise task supporte trois syntaxes pour définir des tasks.

Dans le fichier .mise.toml, en ligne simple :

[tasks.build]
run = "pnpm run build"

Ou en bloc multiligne :

[tasks.clean]
run = """
if [ "$1" = "--with-lint" ]; then
  mise run lint
fi
pnpm run test
"""

Ou alors, via des scripts dans le dossier mise-tasks/, par exemple mise-tasks/build :

#!/usr/bin/env bash
#MISE description="Build the web application"
pnpm run build

Voici un extrait de Mise tasks mises en œuvre dans un vrai projet :

$ mise task
Name                           Description
build-cli                      Build the sklein-devbox CLI application
build-image                    Build the sklein-devbox container image
[...snip...]
up                             Start the devbox container

Le code source est consultable ici : https://github.com/stephane-klein/sklein-devbox/blob/main/.mise.toml

C'est important pour moi de préciser que j'ai bien conscience que Mise Tasks est une couche de plus — et que ça contredit ma doctrine « enlever des couches ».
Dans un projet d'équipe, je partirais par défaut sur des scripts Bash simples, sans Mise task. Je n'intégrerais Mise task que s'il y a un consensus fort de l'équipe — et je ne l'imposerais pas.

Remerciements

Je remercie mes deux amis de m'avoir motivé à écrire cette note — c'est un sujet que je souhaitais traiter depuis 2019 (j'avais même créé une issue à ce sujet dans mon ancien backlog).

Voici une nouvelle fonctionnalité qui illustre pourquoi j'apprécie l'expérience développeur (DX) de SvelteKit : la simplicité d'accès aux variables d'environnement !

Je commence avec un peu de contexte.

Comme je l'ai déjà dit dans une précédente note, je suis depuis 2015 les principes de The Twelve-Factors App.

Concrètement, quand je déploie un frontend web qui a besoin de paramètres de configuration, par exemple une URL pour accéder à une API, je déploie quelque chose qui ressemble à ceci :

# docker-compose.yml
services:
  webapp:
    image: ...
    environment:
      GRAPHQL_API: https://example.com/

De 2012 à 2022, quand ma doctrine était de produire des frontend web en SPA, j'avais recours à du boilerplate code à base de commande sed dans un entrypoint.sh, qui avait pour fonction d'attribuer des valeurs aux variables de configuration — comme dans cet exemple GRAPHQL_API — au moment du lancement du container Docker, exemple : entreypoint.sh.

Ce système était peu élégant, difficile à expliquer et à maintenir.

Ce soir, j'ai découvert les fonctionnalités suivantes de SvelteKit :

J'ai publié ce playground sveltekit-environment-variable-playground qui m'a permis de tester ces fonctionnalités dans un projet SSR avec hydration.

J'ai testé comment accéder à trois variables dans trois contextes différents (.envrc) :

# Set at application build time
export PUBLIC_VERSION="0.1.0" 

# Set at application startup time and accessible only on server side
export POSTGRESQL_URL="postgresql://myuser:mypassword123@localhost:5432/mydatabase"

# Set at application startup time and accessible on frontend side
export PUBLIC_GOATCOUNTER_ENDPOINT=https://example.com/count

Cela fonctionne parfaitement bien, c'est simple, pratique, un pur bonheur.

Pour plus de détails, je vous invite à regarder le playground et à tester par vous-même.

Merci aux développeurs de SvelteKit ❤️.

J'ai regardé ce que propose NextJS et je constate qu'il propose moins de fonctionnalités.

D'après ce que j'ai compris, NextJS propose l'équivalent de $env/dynamic/private et $env/static/public mais j'ai l'impression qu'il ne propose rien d'équivalent à $env/dynamic/public.

#JaiLu

Rich Harris explains this clearly. JSDoc for writing a lib. TypeScript for writing an app. (from)

Ce conseil entre en opposition avec ce que j'ai écrit en octobre 2023 :

Si je dois coder et publier une librairie sur npm alors, je choisis TypeScript.
Quand je dis librairie, je parle de librairie qui contient des classes, des fonctions ou des composants importés par d'autres projets.

Pourquoi est-ce que je choisis d'utiliser TypeScript pour les librairies ?

Je permets aux développeurs qui utilisent TypeScript dans leur projet, de pouvoir bénéficier de la documentation, l'autocomplétion, la détection des erreurs… de la librairie que j'aurais mise à disposition ;

Je n'ai pas vérifié, mais je pense que le typage de TypeScript permet à des outils d'auto générer une grande partie de la documentation d'une librairie.

Ce conseil entre aussi en opposition avec ce second élément que j'ai écrit en octobre 2023 :

Si je dois coder une application web, alors pour le moment, je choisis JavaScript.
Le code implémenté dans une application web, n'est généralement pas utilisé par des utilisateurs "externes". Par conséquent, je ne trouve pas très important de mettre à disposition une documentation aux autres développeurs. Je pense qu'à petite taille, l'effort ne vaut pas la peine. Ma réponse est peut-être différente si 10, 20… développeurs contribuent à la même base code 🤔.

Généralement, le code d'une application web est plutôt simple, beaucoup de CRUD et peu de librairie complexe.

Pour le moment, je pense que l'effort d'ajouter le boilerplate code de typage TypeScript (importer les types, d'ajouter le typage dans le code) ne sera pas compensé par les fonctionnalités de détection d'erreurs , d'autocomplétions et de refactoring que permet TypeScript.

Je pense qu'il serait bon que je revoie ma doctrine d'artisan développeur sur ce sujet.

Cette après midi, j'hésite à migrer le projet sveltekit-tendaro-webshell-skeleton de Javascript vers TypeScript.

Je me demande si :

cela en vaut la peine ;
étant donné que je n'ai jamais fait pour de vrai un projet en TypeScript, est-ce que je ne risque pas de tomber dans un Yak! 🤔.

Actuellement ma doctrine concernant TypeScript est la suivante.

Si je dois coder et publier une librairie sur npm alors, je choisis TypeScript.
Quand je dis librairie, je parle de librairie qui contient des classes, des fonctions ou des composants importés par d'autres projets.

Pourquoi est-ce que je choisis d'utiliser TypeScript pour les librairies ?

Je permets aux développeurs qui utilisent TypeScript dans leur projet, de pouvoir bénéficier de la documentation, l'autocomplétion, la détection des erreurs… de la librairie que j'aurais mise à disposition ;
Je n'ai pas vérifié, mais je pense que le typage de TypeScript permet à des outils d'auto générer une grande partie de la documentation d'une librairie.

Si je dois coder une application web, alors pour le moment, je choisis JavaScript.
Le code implémenté dans une application web, n'est généralement pas utilisé par des utilisateurs "externes". Par conséquent, je ne trouve pas très important de mettre à disposition une documentation aux autres développeurs. Je pense qu'à petite taille, l'effort ne vaut pas la peine. Ma réponse est peut-être différente si 10, 20… développeurs contribuent à la même base code 🤔.

Généralement, le code d'une application web est plutôt simple, beaucoup de CRUD et peu de librairie complexe.
Pour le moment, je pense que l'effort d'ajouter le boilerplate code de typage TypeScript (importer les types, d'ajouter le typage dans le code) ne sera pas compensé par les fonctionnalités de détection d'erreurs , d'autocomplétions et de refactoring que permet TypeScript.

Mais je me dis que je me trompe peut-être, peut-être que si j'essaie, je vais me rendre compte que j'aime bien cela et que cela me fera gagner du temps ou alors améliorera mon confort, mon plaisir de développement 🤔.

Tâches à faire si je souhaite migrer à TypeScript :

[ ] Implémenter une déclinaison de sveltekit-ssr-skeleton en TypeScript
[ ] Modifier mon environnement Neovim pour activer les fonctionnalités suivantes :
- [ ] Support de l'autocomplétion TypeScript
- [ ] Support de la détection des erreurs TypeScript
- [ ] Support des fonctions de refactoring TypeScript
- [ ] Affichage en "live" de la documentation des composants, fonctions…

Ressources à lire avant pour avancer sur ce sujet :